doc/design-doc/2.5.attr-structured variable define.txt

   1
   2
   3
   4
   5
   6 [tmp]
   7 @ *, & is used for cmdline, define ^ and % for addressing and addressed.
   8   # ^ is used for addressing,
   9   # % is used for get address.
  10   # ^^ is used for string name reference, it's equal to ${!ref}
  11   # %% is used for get env var name of referenced var.
  12 @ a->b is not a permitted string in cmd, '>' will be treated as re-direction.
  13   # use a:-:b instead of '->'.
  14   # so does the ':=:' for '=>', it's a string name reference accessing.
  15 @ ; is used in cmdline, define ',,' as it's feature in prog lang.
  16 @ variable type of ref, it's equal to a 'pointer', but the address is instead
  17   by env var name.
  18 @ variable type of function, it defines a variable with general function name.
  19 @
  20
  21 [char-in-variable-string]
  22 @ started with '@' for using and assignment.
  23 @ ^ or % or ^^ or %%,
  24 @ :: or .,
  25 @ :-: or :=:,
  26 @
  27
  28
  29
  30
  31
  32
  33 # introduction
  34
  35
  36
  37 # conception
  38
  39
  40
  41 # function invoking
  42 ===================
  43
  44     () can note be used as a normal string, but use as @().
  45
  46 $ echo test string @(abc())
  47 test string @(abc())
  48
  49     this can be used for function invoking.
  50
  51 # variable
  52 ==========
  53
  54 .   type of environment variable.
  55
  56 @ env, pure envrionment variable.
  57 @ attr, attribute variable. it uses '::' to express level relationship between
  58   member variables, and use '__' to save as a env var.
  59 @ type, define type structure.
  60 @ entity, it's a struectured variable with multi-sub-member.
  61 @ struct, like a container to store several attr variable.
  62 @ union, the conception in c-lang. it's single entity with different types.
  63 @ enum, actually, it's a single var, but the defination in grammar like a form
  64   of multi element.
  65 @ inherit, it's an operation of type define. it defined a type from another
  66   type. although, it's no need for a cmdline script language, but it's a
  67   feature for programming language.
  68
  69 ## env & attr & entity
  70
  71 .   all various kind of element uses env var accessing, method of element using
  72 is the transform of env var name. so, define the fundamential env var operating
  73 function interface as the low-level adeptor.
  74
  75 .   attr, attribute variable. it uses '::' to express levelized relationship
  76 between member variables, and save as an env var with connection char of '__'.
  77 it's a simple method to orgnize variable in structure.
  78
  79 .   entity is relatived with a type, and can be re-defined with different
  80 entity name. the member object can be var/func/ref/entity/tdv(type-defined-var)
  81 in static or non-static.
  82 .   may be the conception of entity is a bit like struct in objc.
  83
  84
  85
  86 ## type
  87
  88 .   kinds of type and var:
  89
  90 @ fundamental-type, only consisted by one var.
  91   + in shell script, it only support string and integer.
  92   + by extending, it defines hex/bcd/bool/bit/oct on string operation.
  93   + by builtin extending, it defines var type in actual var type.
  94 @ structured-type, it contain multiple member in a type defination. type is a
  95   genernal name for structured type, it defined by struct/union/enum.
  96 @ type-defined-var, var defination combined with structured type defination.
  97 @ entity, var defination by the type defined independently.
  98
  99 .   for example:
 100 @ env_var; string szName; int32 i32Value; BCD bcdData; float32 f32Value;
 101 @ struct __tag_STR_TYPE { ... } STR_VAR, *PSTR_VAR;
 102 @ type struct __tag_STR_TYPE2 { ... } STR_TYPE2, *PSTR_TYPE2;
 103 @ entity STR_TYPE2 stVarTest, *pstVarTest;
 104
 105 .   however, type/entity/struct/union/enum is a multi-member object. in
 106 the structure, it contains:
 107
 108 @ type-defined-var, it's a structure contains sub member without type define.
 109 @ entity, same as type-var, but the type is define independently.
 110 @ variable, data variable as normal, except the structured prefix.
 111 @ function, function in structured object.
 112 @ reference, it's equal to ${!ref}, variable content is the name of another
 113   variable.
 114
 115 .   type/entity/struct/union/enum contains sub-members in defination. if the
 116 sub-member also contains sub-member, there are several kind of conditions:
 117 @ direct define with parent variable prefix.
 118 @ store TYPE info like 'TYPE type tyename1', or 'TYPE struct structname1', or
 119   'TYPE union unionname1', or 'TYPE enum enumname1'.
 120
 121 > @ if a type/struct/union/enum contains sub-type,
 122     + store sub-type info in type var, whatever it's static or non-static.
 123 > @ if an entity contains sub-type, declare with var name prefix.
 124 >>  + put static member list into entity var, accessing by reference method.
 125 >>  + declare non-static member with entity and member var prefix.
 126
 127
 128 @ two purpose of using:
 129 # general xml doc dispatch, and store the dispatched data.
 130 # bin/hex format data dispatch. for protocol or file format.
 131
 132
 133 eg:
 134 @ env
 135 VARIABLE_ABC
 136
 137 @ attr
 138 ::domain::variable::subitem
 139 :: means ATTR__ prefix for global.
 140
 141 @ type
 142 T::DOMMAIN::TYPE_NAME
 143 {
 144         member,,
 145         dir,,
 146         dir::submember,,
 147         array[10],,
 148         reference,,
 149         function,,
 150 }
 151 TV::DOMMAIN::TYPE_NAME::static_member
 152 TD::DOMMAIN::TYPE_NAME::static_dir
 153 TV::DOMMAIN::TYPE_NAME::static_dir::submember
 154 TV::DOMMAIN::TYPE_NAME::static_array[10]
 155 TR::DOMMAIN::TYPE_NAME::static_reference
 156 TF::DOMMAIN::TYPE_NAME::static_function
 157
 158 @ entity
 159 ::domain::variable.subitem
 160   ::domain::variable, is a normal attr. it reference to 'E::variable'.
 161 E::variable, is an entity.
 162 ED::variable::dir, is a member struct in attr variable.
 163 EV::variable::member, is a member variable in attr variable.
 164 ER::variable::reference, is a member ref in attr variable.
 165 EF::variable::function, is a member function in attr variable.
 166
 167 @ example
 168 # using '\\\' after '//' comment. it will ignore string between '//' and '\'
 169 # in a c code, all char aflter // is commented, including '\'. it's not a line
 170 # continous char in c comment. this code compatible with c and shell script.
 171 entity TYPE_NAME eVarName = { // comment \\\
 172         .member = 'member value',, \
 173         .dir = { \
 174                 .submember = 'submember value',, \
 175         },, \
 176         .array = { 1 ... },, \
 177 },,
 178 attr_get @eVarName.member
 179 attr_get @eVarName.static_member
 180 attr_get @eVarName.dir.submember
 181 attr_get @eVarName.static_dir.submember
 182 attr_get @eVarName.array[1]
 183 attr_get @^^eVarName.reference
 184 attr_get @^^eVarName.static_reference
 185 attr_invoke @eVarName.function
 186 attr_invoke @eVarName.static_function
 187
 188 entity TYPE_NAME tmpdomain::eVarName,,
 189 attr_get @tmpdomain::eVarName.member
 190
 191 attr_set @tmpdomain::eVarName.reference = @%%eVarName
 192 attr_get @tmpdomain::eVarName.reference:=:member
 193 attr_get @tmpdomain::eVarName.reference:=:static_member
 194 attr_get @tmpdomain::eVarName.reference:=:dir.submember
 195 attr_get @tmpdomain::eVarName.reference:=:static_dir.submember
 196 attr_invoke @tmpdomain::eVarName.reference:=:function
 197 attr_invoke @tmpdomain::eVarName.reference:=:static_function
 198
 199 attr_set @tmpdomain::eVarName.reference = @%%eVarName.member
 200 attr_get @^^tmpdomain::eVarName.reference
 201
 202 typedef struct __tag_STR_TEST { \
 203         var1, var2,, \ #  = 'value of var1' assignement is not allowed.
 204         static var3 = 'static value of var3',, \
 205         const static var4 = 'const static value of var4',, \
 206 } STR_TEST, *PSTR_TEST,,
 207
 208 entity STR_TEST strVar = { \
 209         .var1 = 'value for var1',, \
 210         .var2 = 'value for var2',, \
 211         .var3 = 'new value for var3',, \
 212 },,
 213
 214 attr_get @strVar.var1
 215 attr_get @strVar.var2
 216 attr_get @strVar.var3
 217 attr_get @strVar.var4
 218
 219
 220 [using]
 221 @ operation:
 222 # defination/decleration/get/set/accessing by func.
 223 # defination/decleration/get/set/accessing by reserved word.
 224 @ type:
 225 # defination,
 226 # decleration, with the cmd of 'entity' or '@'.
 227 # initialization, in defination or decleration.
 228 # get, accessing, by the char of '@', or using operation function.
 229 # set, using '@', and the first char of first paramter is '@', it's an
 230   assignment operation.
 231 #
 232
 233
 234 # var name
 235 ==========
 236
 237     there are several different level for name of var:
 238 @ '@{%%::domain::varname.function[[paramter1, paramter2]]}', it's the whole var
 239   name string.
 240 @ '::domain::varname.function', it's the variable symbol name.
 241 @ 'domain', or 'varname', or 'function', it's the name element string.
 242
 243     a variable name dispatching work, is to get the whole var name string in
 244 a general string, and dispatch them into name element strings.
 245
 246
 247 @ start with '@'. use this prefix every where, even if it is a decleration and
 248   assignment.
 249 @ special char after '@' is:
 250 # '{' or '(', it's the boundary char for variable define.
 251 # '^', it means variable is a pointer with physical memory address, it point to
 252   the content with the type writen in pointer var.
 253 # '%', it's the char of address getting.
 254 # '-', it's the connector for '^' and '%', it means the pointer's pointer. it
 255   is used for 'type **var' in c style, does not mean the pointer of 'type
 256   @*var'.
 257 # '^^', it means reference pointer. variable is a reference, it include the
 258   name of dest var, and type of dest var.
 259 # '%%', get the name and type info for the dest var, and it is used to assign
 260   reference info to a reference var.
 261 # '@', dual '@' means print the content of variable.
 262 # '::', it's not special char for variable, it's the domain prefix of variable.
 263 @ variable name
 264 # '::', global domain preifx. if it is in the middle of variable, it means the
 265   tree level of variable.
 266 # '[[:alnum:]]_', single variable body name string.
 267 # '.', sub item in structure.
 268 # ':-:', previous var is a memory address pointer, it point to a struct, and
 269   the string after it is the sub-member in dest address.
 270 # ':=:', previous var is a reference var, it reference to a struct variable,
 271   and the string after it is the sub-member in deest reference variable.
 272 @ [] and [[]]
 273 # '[]', it means the element in a original data array.
 274 # '[[]]', it means the function paramter list.
 275 @ {} and ()
 276 # '{}', it include whole variable string in it. it can be dispatched easily.
 277 # '()', it is a compatiable operation for @().
 278 # '@' can be dispatched nestly in '{}' or '()'.
 279
 280
 281
 282
 283
 284
 285
 286
 287 @ list type member
 288 # set global preifx with var name of type defination.
 289 # get tyepname with T::<type>.
 290 # list var with T[VFR]::<type> prefix.
 291 # get subtype from TT::<type>::<typevar>.
 292 # list var with T::<subtype> prefix for every TT member var.
 293
 294 @ list entity member
 295 # get var name to ::<domain>::<vname> without '.' member variable
 296 # get type name from var content. eg: "TYPEDEF TTypeName".
 297 # get member name from var name without domain prefix, but leave '.' subitem.
 298 # list static member with ::<domain>::<type> prefix by the method of last
 299   section.
 300 # list run-time member by E[VFR]::<vname> prefix.
 301 # get subtype from TD::<vname>::<dirvar>.
 302 # list var with T::<subtype> prefix for every TD member var.
 303
 304 @ list attr in entity member
 305 # get attr var in entity
 306 # list member in attr var.
 307
 308
 309 dvar int abc;
 310 dvar struct {member1,, type2 member2,,} vstruct1, vstruct2;
 311 dtype struct {member1,, type2 member2,,} TType1, TType2;
 312 dvar TType1 test1, test2;
 313
 314
 315
 316 ##
 317
 318
 319
 320 ## entity
 321
 322
 323
 324
 325